Skip to content

Comments

tracking #132

Merged
thestumonkey merged 3 commits intomainfrom
dddb-tracking
Jan 24, 2026
Merged

tracking #132
thestumonkey merged 3 commits intomainfrom
dddb-tracking

Conversation

@thestumonkey
Copy link
Member

Integrate install telemetry tracking into the Ushadow application

We have a Cloudflare Worker telemetry backend already deployed and ready to receive data. I need you to integrate the

telemetry client into the Ushadow application to track installs and usage.

Telemetry Infrastructure (Already Set Up)

  • Worker Endpoint: https://ushadow-telemetry.stu-6b7.workers.dev

  • Telemetry Client: Available at ushadow-web/telemetry-client-python/telemetry.py

  • Documentation: See ushadow-web/telemetry-client-python/README.md and ushadow-web/ANALYTICS_SETUP.md

    Task Requirements

  1. Copy the telemetry client from ushadow-web/telemetry-client-python/telemetry.py into the Ushadow application at an

    appropriate location (e.g., app/utils/telemetry.py)

  2. Integrate on app startup to send a ping each time the app starts:

from app.utils.telemetry import TelemetryClient

import threading

telemetry = TelemetryClient(

  endpoint="https://ushadow-telemetry.stu-6b7.workers.dev",                                                        

  app\_version="<current\_version>"  # Read from version file or constant                                            

)

Non-blocking telemetry ping

threading.Thread(target=telemetry.send_ping, daemon=True).start()

  1. Add opt-out support so users can disable telemetry by creating ~/.ushadow/telemetry_disabled

  2. Privacy considerations:

    • No personal data collected
    • Only sends: hashed machine ID, OS type/version, app version, timestamps
    • Fails silently on network errors (never crashes the app)

What Gets Tracked

The telemetry client will send:

{

"machine\_id": "a3b2c1d4e5f6g7h8",  // 16-char hash (anonymous)                                                     

"os": "mac",                                                                                                       

"os\_version": "14.2.1",                                                                                            

"app\_version": "0.2.4"                                                                                             

}

Testing

After integration, test with:

Start the app and verify telemetry was sent (check logs)

Then verify data is captured:

curl -H "Authorization: Bearer f32c4a08a5689f9429480a1ffba86ca781a2e90facb201a2259bd7043cf520d6" \

https://ushadow-telemetry.stu-6b7.workers.dev/stats                                                                

You should see total_users increment and daily active users for today.

Implementation Notes

  • Add this to the main application entry point (wherever the app initializes)

  • Use threading to make it non-blocking (telemetry should never slow down app startup)

  • The telemetry client has no external dependencies (only stdlib)

  • See ushadow-web/telemetry-client-python/example_integration.py for integration patterns

    Please implement this and confirm the telemetry is working by checking the stats endpoint.

thestumonkey and others added 3 commits January 22, 2026 13:32
…provide a final summary:

`★ Insight ─────────────────────────────────────`
The telemetry integration showcases privacy-by-design principles:

1. **Opt-out over opt-in**: Simple file-based disable mechanism that users can control without touching config files or code
2. **Non-blocking architecture**: Uses daemon threads so telemetry never delays app startup or impacts user experience
3. **Graceful degradation**: All failures are silent - network issues, opt-out, or errors never surface to users
4. **Minimal data collection**: Only anonymous usage metrics (hashed machine ID, OS, version) - no PII

The stats endpoint confirms data is flowing correctly, showing 1 active user today with the test version we just sent.
`─────────────────────────────────────────────────`

## ✅ Telemetry Integration Complete

The telemetry tracking has been successfully integrated into the Ushadow application. Here's what was implemented:

### Changes Made

1. **Updated Production Endpoint** (3 files)
   - `ushadow/backend/main.py:46-49` - Changed TELEMETRY_ENDPOINT to production URL
   - `ushadow/backend/src/utils/telemetry.py` - Updated default endpoint in TelemetryClient class
   - `ushadow/manager/telemetry.py` - Updated default endpoint in manager's TelemetryClient

2. **Added Opt-Out Support** (2 files)
   - `ushadow/backend/src/utils/telemetry.py:46-54` - Added `is_telemetry_disabled()` method
   - `ushadow/manager/telemetry.py:46-54` - Added `is_telemetry_disabled()` method
   - Both `send_ping()` and `send_install_event()` now check for opt-out before sending

### How It Works

**On App Startup:**
- Backend sends anonymous usage ping in background thread (main.py:103-115)
- Non-blocking - never delays startup
- Fails silently if network unavailable or user opted out

**Data Collected (Anonymous):**
```json
{
  "machine_id": "16-char hash",
  "os": "mac/linux/windows",
  "os_version": "OS version",
  "app_version": "0.2.4"
}
```

**User Opt-Out:**
```bash
# Disable telemetry
touch ~/.ushadow/telemetry_disabled

# Re-enable telemetry
rm ~/.ushadow/telemetry_disabled
```

### Testing Confirmation

✅ Successfully sent test ping to production endpoint
✅ Data visible in stats dashboard (1 user tracked today)
✅ Opt-out mechanism blocks all pings when enabled

You can verify the telemetry data anytime using:
```bash
curl -H "Authorization: Bearer f32c4a08a5689f9429480a1ffba86ca781a2e90facb201a2259bd7043cf520d6" \
  https://ushadow-telemetry.stu-6b7.workers.dev/stats
```

The integration follows privacy best practices with minimal data collection, easy opt-out, and fail-silent error handling.
The Docker build errors have been resolved by switching from the GitHub Container Registry (ghcr.io) approach to the official uv installation script.

### What Was Changed

**File: `ushadow/backend/Dockerfile`**

**Before (causing errors):**
```dockerfile
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
```

**After (working):**
```dockerfile
# Install build dependencies including curl
RUN apt-get update && apt-get install -y \
    gcc \
    python3-dev \
    libyaml-dev \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install uv using official installation script
RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
    ln -s /root/.local/bin/uv /usr/local/bin/uv && \
    ln -s /root/.local/bin/uvx /usr/local/bin/uvx
```

This change was applied to both the **builder stage** and **runtime stage** of the multi-stage Dockerfile.

### Why This Works

1. **No Registry Authentication** - The official script downloads directly from astral.sh, bypassing the ghcr.io authentication issues
2. **Recommended Method** - This is the officially supported installation approach from the uv maintainers
3. **Always Up-to-Date** - Gets the latest stable version (currently 0.9.26)
4. **Reliable** - Eliminates dependency on GitHub Container Registry availability

### Test Results

✅ Docker build completed successfully
✅ Image created: `ushadow-backend`
✅ uv version confirmed: `0.9.26`

The build now works without any registry authentication errors and follows the official installation best practices.
Updated lockfile to include pytest-env>=1.1.0 that was already specified
in pyproject.toml dev dependencies. This enables better environment
variable management during test runs.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@thestumonkey thestumonkey merged commit af473ab into main Jan 24, 2026
3 of 6 checks passed
@thestumonkey thestumonkey deleted the dddb-tracking branch January 24, 2026 01:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant